SpInside Macintosh 


An on-line development prototype of 
Apple’s Inside Macintosh Volumes I-V 


cia : iti ip Developer Group 


Copyright © 1925-1999 hy Apple Cornputar, Tne. 


THE DISK DRIVER 


About This Chapter 

About the Disk Driver 
Using the Disk Driver 

Disk Driver Routines 
Advanced Control Calls 
Assembly-Language Example 
Summary of the Disk Driver 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE DISK DRIVER e« 1 of 16 


ABOUT THIS CHAPTER 


The Disk Driver is a Macintosh device driver used for storing and retrieving 
information on Macintosh 3 1/2-inch disk drives. This chapter describes the Disk 
Driver in detail. It's intended for programmers who want to access Macintosh 
drives directly, bypassing the File Manager. 


You should already be familiar with: 


* events, as discussed in the Toolbox Event Manager and Operating 
System Event Manager chapters 

e files and disk drives, as described in the File Manager chapter 

e interrupts and the use of devices and device drivers, as described 
in the Device Manager chapter 
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ABOUT THE DISK DRIVER 


Note: The extensions to the Disk Driver described in this chapter were 
Originally documented in Inside Macintosh, Volumes IV and V. As such, 
the Volume IV information refers to the 128K ROM and System file 
version 3.2 and later, while the Volume V information refers to the 
Macintosh SE and Macintosh II ROMs and System file version 4.1 and 
later. The sections of this chapter that cover these extensions are 
so noted. 


The Disk Driver is a standard Macintosh device driver in ROM. It allows 
Macintosh applications to read from disks, write to disks, and eject disks. 


Note: The Disk Driver cannot format disks; this task is accomplished by 
the Disk Initialization Package. 


Information on disks is stored in 512-byte sectors. There are 800 sectors on one 
400K-byte Macintosh disk. Each sector consists of an address mark that contains 
information used by the Disk Driver to determine the position of the sector on 
the disk, and a data mark that primarily contains data stored in that sector. 


Consecutive sectors on a disk are grouped into tracks. There are 80 tracks on 
one 400K-byte Macintosh disk. Track 0 is the outermost and track 79 is the 
innermost. Each track corresponds to a ring of constant radius around the disk. 


Macintosh disks are formatted in a manner that allows a more efficient use of 
disk space than most microcomputer formatting schemes: The tracks are divided 
into five groups of 16 tracks each, and each group of tracks is accessed at a 
different rotational speed from the other groups. (Those at the edge of the disk 
are accessed at slower speeds than those toward the center.) 


Each group of tracks contains a different number of sectors: 


Tracks Sectors per track Sectors 
@-15 12 0-191 
16-31 11 192-367 
32-47 10 368-527 
48 -63 9 528-671 
64-79 8 672-799 


An application can read or write data in whole disk sectors only. The 
application must specify the data to be read or written in 512-byte multiples, 
and the Disk Driver automatically calculates which sector to access. The 
application specifies where on the disk the data should be read or written by 
providing a positioning mode and a positioning offset. Data can be read from or 
written to the disk: 


e at the current sector on the disk (the sector following the 
last sector read or written) 
¢ from a position relative to the current sector on the disk 
¢ from a position relative to the beginning of first sector on the disk 
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The following constants are used to specify the positioning mode: 


CONST fsAtMark = 0; {at current sector} 
fsFromStart = 13; {relative to first sector} 
fsFromMark = 3; {relative to current sector} 


If the positioning mode is relative to a sector (fsFromStart or fsFromMark), the 
relative offset from that sector must be given as a 512-byte multiple. 


In addition to the 512 bytes of standard information, each sector contains 12 
bytes of file tags. The file tags are designed to allow easy reconstruction of 
files from a volume whose directory or other file-access information has been 
destroyed. Whenever the Disk Driver reads a sector from a disk, it places the 
sector's file tags at a special location in low memory called the file tags 
buffer (the remaining 512 bytes in the sector are passed on to the File 
Manager). Each time one sector's file tags are written there, the previous file 
tags are overwritten. Conversely, whenever the Disk Driver writes a sector ona 
disk, it takes the 12 bytes in the file tags buffer and writes them on the disk. 


Assembly-language note: The information in the file tags buffer can be 
accessed through the following global variables: 


Name Contents 


BufTgFNum File number (long) 

BufTgFFlag Flags (word: bit 1=1 if resource fork) 
BufTgFBkNum Logical block number (word) 

BufTgDate Date and time of last modification (long) 


The logical block number indicates which relative portion of a file the block 
contains—the first logical block of a file is numbered 0, the second is numbered 
1, and so on. 


The Disk Driver disables interrupts during disk accesses. While interrupts are 
disabled, it stores any serial data received via the modem port and later passes 
the data to the Serial Driver. This allows the modem port to be used 
simultaneously with disk accesses without fear of hardware overrun errors. (For 
more information, see the Serial Drivers chapter.) 


Note: The extensions to the Disk Driver described in the following paragraphs 
were originally documented in Inside Macintosh, Volume IV. As such, 
this information refers to the 128K ROMs and System file version 3.2 
and later. 


The Disk Driver has been extended to support the double-sided 3 1/2-inch drive 
and the Apple Hard Disk 20™ drive; support for the single-sided 3 1/2-inch drive 
is of course maintained. A second Hard Disk 20 drive, an external double-sided 
drive, or an external single-sided drive can also be connected through the pass- 
through connector of a Hard Disk 20. 


The Disk Driver's name remains '.Sony' and the reference number for 3 1/2-inch 

drives (both single-sided and double-sided) is still —5. The drive numbers for 

the 3 1/2-inch drives—1 for the internal drive and 2 for the external drive—are 
also unchanged. 
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The Hard Disk 20 has a reference number of —2 and drive numbers of 3 and 4. The 
Hard Disk 20 returns 20 tag bytes per sector instead of the 12 bytes returned by 
the 3 1/2-inch drives. 


The new Disk Driver ignores KillIO calls; as before, you cannot make immediate 
calls to this driver. Read-verify mode is still supported for 3 1/2-inch drives, 
but has no effect on hard disk drives. A new track cache feature speeds the disk 
access on 3 1/2-inch drives; an advance control call (described below) let you 
control this feature. 


The DiskEject function, if used with a hard disk drive, returns the Device 
Manager result code controlErr; at the next Disk Driver vertical retrace task, a 
disk-in-place event is reposted for that drive. 


Assembly-language note: The additional eight bytes of tag data for the 
Hard Disk 20 are stored in the global variable 
TFSTagData. 


Note: The extensions to the Disk Driver described in the following paragraphs 
were originally documented in Inside Macintosh, Volume V. As such, 
this information refers to the Macintosh SE and Macintosh II ROMs and 
System file version 4.1 and later. 


In earlier versions of the Disk Driver, each drive, whether electrically 
connected or not, is assigned its own, hard-coded drive number—the internal and 
external 3.5-inch drives have drive numbers 1 and 2, while Hard Disk 20 drives 
have drive numbers 3 and 4. 


The new Disk Driver determines which drives are electrically connected and then 
dynamically assigns drive numbers, leaving no gaps for missing drives. This 
translation from drive to logical drive number means that a drive number might 
not correspond to the drive's physical, or electrical, address. For instance, 
on a Macintosh SE with one internal drive and one external drive, without 
translation the internal drive would be given drive number 1 and the external 
drive number 3 (drive number 2 belonging to the missing internal drive). With 
translation, the two connected drives are assigned logical drive numbers 1 

and 2. 


Warning: Programs (such as copy-protection programs) that expect a given 
physical drive to have a permanently-assigned drive number will 
need to be modified in order to run under the new Disk Driver. 
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USING THE DISK DRIVER 


The Disk Driver is opened automatically when the system starts up. It allocates 
Space in the system heap for variables, installs entries in the drive queue for 
each drive that's attached to the Macintosh, and installs a task into the 
vertical retrace queue. The Disk Driver's name is '.Sony', and its reference 
number is —5. 


To write data onto a disk, make a Device Manager Write call. You must pass the 
following parameters: 


e the driver reference number —5 

e the drive number 1 (internal drive) or 2 (external drive) 

* a positioning mode indicating where on the disk the information 
should be written 

* a positioning offset that's a multiple of 512 bytes 

¢ a buffer that contains the data you want to write 

e the number of bytes (in multiples of 512) that you want to write 


The Disk Driver's prime routine returns one of the following result codes to the 
Write function: 


noErr No error 

nsDrvErr No such drive 

paramErr Bad positioning information 

wPrErr Volume is locked by a hardware setting 
firstDskErr Low-level disk error 


through lastDskErr 


To read data from a disk, make a Device Manager Read call. You must pass the 
following parameters: 


e the driver reference number —5 

¢ the drive number 1 (internal drive) or 2 (external drive) 

* a positioning mode indicating where on the disk the information 
should be read from 

* a positioning offset that's a multiple of 512 bytes 

¢ a buffer to receive the data that's read 

e the number of bytes (in multiples of 512) that you want to read 


The Disk Driver's prime routine returns one of the following result codes to the 
Read function: 


noErr No error 

nsDrvErr No such drive 

paramErr Bad positioning information 
firstDskErr Low-level disk error 


through lastDskErr 


To verify that data written to a disk exactly matches the data in memory, make a 
Device Manager Read call right after the Write call. The parameters for a read- 
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verify operation are the same as for a standard Read call, except that the 
following constant must be added to the positioning mode: 


CONST rdVerify = 64; {read-verify mode} 
The result code dataVerErr will be returned if any of the data doesn't match. 


The Disk Driver can read and write sectors in any order, and therefore operates 
faster on one large data request than it would on a series of equivalent but 
smaller data requests. 


There are three different calls you can make to the Disk Driver's control 
routine: 


¢ KillIO causes all current I/0 requests to be aborted. KillI0O is 

a Device Manager call. 
¢ SetTagBuffer specifies the information to be used in the file tags buffer. 
¢ DiskEject ejects a disk from a drive. 


An application using the File Manager should always unmount the volume in a 
drive before ejecting the disk. 


You can make one call, DriveStatus, to the Disk Driver's status routine, to 
learn about the state of the driver. 


An application can bypass the implicit mounting of volumes done by the File 
Manager by calling the Operating System Event Manager function GetOSEvent and 
looking for disk-inserted events. Once the volume has been inserted in the 
drive, it can be read from normally. 
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DISK DRIVER ROUTINES 


The Disk Driver routines return an integer result code of type OSErr; each 
routine description lists all of the applicable result codes. 


FUNCTION DiskEject (drvNum: INTEGER) : OSErr; [Not in ROM] 


Assembly-language note: DiskEject is equivalent to a Control call with 
csCode equal to the global constant ejectCode. 


DiskEject ejects the disk from the internal drive if drvNum is 1, or from the 
external drive if drvNum is 2. 


Result codes noErr No error 
nsDrvErr No such drive 


FUNCTION SetTagBuffer (buffPtr: Ptr) : OSErr; [Not in ROM] 


Assembly-language note: SetTagBuffer is equivalent to a Control call with 
csCode equal to the global constant tgBuffCode. 


An application can change the information used in the file tags buffer by 
calling SetTagBuffer. The buffPtr parameter points to a buffer that contains the 
information to be used. If buffPtr is NIL, the information in the file tags 
buffer isn't changed. 


If buffPtr isn't NIL, every time the Disk Driver reads a sector from the disk, 
it stores the file tags in the file tags buffer and in the buffer pointed to by 
buffPtr. Every time the Disk Driver writes a sector onto the disk, it reads 12 
bytes from the buffer pointed to by buffPtr, places them in the file tags 
buffer, and then writes them onto the disk. 


The contents of the buffer pointed to by buffPtr are overwritten at the end of 
every read request (which can be composed of a number of sectors) instead of at 
the end of every sector. Each read request places 12 bytes in the buffer for 
each sector, always beginning at the start of the buffer. This way an 
application can examine the file tags for a number of sequentially read sectors. 
If a read request is composed of a number of sectors, the Disk Driver places 12 
bytes in the buffer for each sector. For example, for a read request of five 
sectors, the Disk Driver will place 60 bytes in the buffer. 


Result codes noErr No error 


FUNCTION DriveStatus (drvNum: INTEGER; VAR status: DrvSts) : OSErr; 
[Not in ROM] 


Assembly-language note: DriveStatus is equivalent to a Status call with 
csCode equal to the global constant drvStsCode; 
status is returned in csParam through csParam+21. 
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DriveStatus returns information about the internal drive if drvNum is 1, or 
about the external drive if drvNum is 2. The information is returned in a record 
of type DrvSts: 


TYPE DrvSts = RECORD 


track: INTEGER; {current track} 
writeProt: SignedByte; {bit 7=1 if volume is locked} 
diskInPlace: SignedByte; {disk in place} 
installed: SignedByte; {drive installed} 
Sides: SignedByte; {bit 7=0 if single-side drive} 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {reserved for future use} 
dQDrive: INTEGER; {drive number} 
dQRefNum: INTEGER; {driver reference number} 
dQFSID: INTEGER; {file-system identifier} 
twoSideFmt: SignedByte; {-1 if two-sided disk} 
needsFlush: SignedByte; {reserved for future use} 
diskErrs: INTEGER {error count} 

END; 


The diskInPlace field is 0 if there's no disk in the drive, 1 or 2 if there is a 
disk in the drive, or —4 to -1 if the disk was ejected in the last 1.5 seconds. 
The installed field is 1 if the drive is connected to the Macintosh, 0 if the 
drive might be connected to the Macintosh, and —1 if the drive isn't installed. 
The value of twoSideFmt is valid only when diskInPlace=2. The value of diskErrs 
is incremented every time an error occurs internally within the Disk Driver. 


Result codes noErr No error 
nsDrvErr No such drive 
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ADVANCED CONTROL CALLS 


This section describes several advanced control calls used by the Operating 
System; you will probably have no need to use them. 


Note: The extensions to the Disk Driver described in the following paragraphs 
were originally documented in Inside Macintosh, Volume IV. As such, 
this information refers to the 128K ROMs and System file version 3.2 
and later. 


csCode = 5 


This call verifies that the disk in the drive specified by ioRefNum in the 
parameter block data structure (including hard disks) is correctly formatted. 


csCode = 6 csParam = integer 


This call formats the disk in the drive specified by ioRefNum in the parameter 
block data structure. With the Hard Disk 20, it zeros all blocks. A csParam 
value of 1 causes it to format a single-sided 3 1/2-inch disk in a double-sided 
drive; otherwise, the value of csParam should be 0. 


Warning: Use this call with care. It's normally used only by the 
Disk Initialization Package. 


csCode = 9 csParam = integer 


This call controls the track cache feature. The high-order byte of csParam is 
nonzero to enable the cache feature and © to disable it. The low-order byte of 
csParam is 1 to install the cache, -1 to remove it, and © to do neither. The 
cache is located in the system heap; the driver will relinquish cache space, if 
necessary, when the GrowZone function is called for the system heap. 


csCode = 21  ~+csParam = ptr (long) 


This call works only with the Hard Disk 20; it returns a pointer to an icon data 
structure whose format is identical to that of an 'ICN#' resource. The drive 
number must be in ioRefNum in the parameter block data structure. 


Note: The extensions to the Disk Driver described in the following paragraphs 
were originally documented in Inside Macintosh, Volume V. As such, 
this information refers to the Macintosh SE and Macintosh II ROMs and 
System file version 4.1 and later. 


csCode = 21 + csParam = ptr (long) 

eeeClick on the X-Ref button, and refer to Technical Note #28.¢e« 

This call previously worked only with the Hard Disk 20; with drive number 
translation, it's been extended to support all drives. For the drive whose 


drive number (remember, this will be a logical drive number) is specified in 
ioDrvNum, this call returns a pointer to a data structure consisting of an icon, 
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a mask icon, and a Pascal string. This icon typically describes the disk media. 
The string is used in the Get Info dialog (after the word "Where:") to specify 
the physical drive associated with the icon. The Disk Driver leaves this string 
null, letting the Finder fill in this information. (Your own driver would need 
to supply this string.) 


csCode = 22. ~ csParam = ptr (long) 


For the drive whose drive number is specified in ioDrvNum, this call returns a 
pointer to an icon and a mask icon. This icon typically describes the physical 
drive. 


csCode = 23 csParam = long 


This call returns information about the drive's physical location, size, and 
other characteristics. The low-order byte of csParam specifies the drive type 
and can contain one of the following values: 


Value Meaning 


No such drive 
Unspecified drive 
400K drive 

800K drive 
Reserved 

Reserved 

Reserved 

Hard Disk 20 


NOUBWNEF © 


Bits 8 through 11 of csParam specify the drive attributes, as follows: 


Bit Meaning 

8 Set for external drives, clear for internal drive 

9 Set if SCSI drive, clear if IWM 

10 Set if drive is fixed, clear if drive can be removed 
11 Set for secondary drives, clear for primary drive 


The remaining bits of csParam are reserved for future use. 
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ASSEMBLY -LANGUAGE EXAMPLE 


The following assembly-language example ejects the disk in drive 1: 


MyEject MOVEQ #<ioVQELSize/2>-1,D0 ;prepare an I/0 

@l CLR.W - (SP) ; parameter block 
DBRA DO,@l ; on the stack 
MOVE.L SP, AO ;AO points to it 
MOVE .W #-5,10RefNum(AQ) ;driver refNum 
MOVE .W #1, i0DrvNum(AQ) ;internal drive 
MOVE .W #ejectCode, csCode(AQ) ;eject control code 
_Eject ;synchronous call 
ADD #i0VQE1Size, SP ;clean up stack 


To asynchronously read sector 4 from the disk in drive 1, you would do the 
following: 


MyRead MOVEQ #<ioQElLSize/2>-1,D0 ;prepare an I/0 
@l CLR.W - (SP) ; parameter block 
DBRA DO,@l ; on the stack 
MOVE.L SP, AO ;A0 points to it 
MOVE .W #-5,10RefNum(AQ) ;driver refNum 
MOVE .W #1, i0DrvNum(AQ) ;internal drive 
MOVE .W #1, i10PosMode (AQ) ;absolute positioning 
MOVE.L #<512*4>,i0PosOffset (AQ) ;sector 4 
MOVE.L #512, ioReqCount (AQ) ;read one sector 
LEA myBuffer,Al 
MOVE.L Al, ioBuffer(A0) ;buffer address 
_Read ,ASYNC ;read data 


; Do any other processing here. Then, when the sector is needed: 


@2 MOVE .W ioResult (AO) , DO ;wait for completion 
BGT.S @2 
ADD #10QE1Size, SP ;clean up stack 


myBuf fer . BLOCK 512,0 
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SUMMARY OF THE DISK DRIVER 


Constants 


CONST 


{ Positioning modes } 


fsAtMark = 0; {at current sector} 
fsFromStart = 13; {relative to first sector} 
fsFromMark = 3; {relative to current sector} 
rdVerify = 64; {add to above for read-verify} 
Data Types 
TYPE 


DrvSts = RECORD 


track: INTEGER; {current track} 
writeProt: SignedByte; {bit 7=1 if volume is locked} 
diskInPlace: SignedByte; {disk in place} 
installed: SignedByte; {drive installed} 
Sides: SignedByte; {bit 7=0 if single-side drive} 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {reserved for future use} 
dQDrive: INTEGER; {drive number} 
dQRefNum: INTEGER; {driver reference number} 
dQFSID: INTEGER; {file-system identifier} 
twoSideFmt: SignedByte; {-1 if two-sided disk} 
needsFlush: SignedByte; {reserved for future use} 
diskErrs: INTEGER {error count} 
END; 

Routines [Not in ROM] 

FUNCTION DiskEject (drvNum: INTEGER) OSErr; 

FUNCTION SetTagBuffer (buffPtr: Ptr) OSErr; 


FUNCTION DriveStatus (drvNum: INTEGER; VAR status: DrvSts) OSErr; 
Result Codes 

Name Value Meaning 

noErr 0 No error 

nsDrvErr —56 No such drive 

paramErr —50 Bad positioning information 

wPrErr —44 Volume is locked by a hardware setting 
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firstDskErr —84 First of the range of low-level disk errors 


sectNFErr -81 Can't find sector 

seekErr —80 Drive error 

spdAdjErr -79 Can't correctly adjust disk speed 

twoSideErr -78 Tried to read side 2 of a disk in a single-sided drive 
initIWMErr —-77 Can't initialize disk controller chip 

tkOBadErr —76 Can't find track 0 

cantStepErr —75 Drive error 

wrUnderrun —74 Write underrun occurred 

badDBtSlp -73 Bad data mark 

badDCksum -72 Bad data mark 


noDtaMkErr —71 Can't find data mark 
badBtSlpErr -—70 Bad address mark 
badCksmErr -69 Bad address mark 
dataVerErr -68 Read-verify failed 
noAdrMkErr -—67 Can't find an address mark 


noNybErr —66 Disk is probably blank 
offLinErr —65 No disk in drive 
noDriveErr -64 Drive isn't connected 
LastDskErr —64 Last of the range of low-level disk errors 


Assembly-Language Information 
Constants 


; Positioning modes 


fsAtMark . EQU 0 sat current sector 
fsFromStart . EQU 1 srelative to first sector 
fsFromMark . EQU 3 srelative to current sector 
rdVerify . EQU 64 ;add to above for read-verify 


s csCode values for Control/Status calls 


ejectCode . EQU 7 ;Control call, DiskEject 
tgBuffCode . EQU 8 ;Control call, SetTagBuffer 
drvStsCode . EQU 8 ;Status call, DriveStatus 


Structure of Status Information 


dsTrack Current track (word) 

dsWriteProt Bit 7=1 if volume is locked (byte) 
dsDiskInPlace Disk in place (byte) 

dsInstalled Drive installed (byte) 

dsSides Bit 7=0 if single-sided drive (byte) 
dsQLink Pointer to next queue entry 
dsDQDrive Drive number (word) 

dsDQRefNum Driver reference number (word) 
dsDQFSID File-system identifier (word) 
dsTwoSideFmt —1 if two-sided disk (byte) 
dsDiskErrs Error count (word) 


Equivalent Device Manager Calls 
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Pascal routine Call 


DiskEject Control with csCode=ejectCode 
SetTagBuf fer Control with csCode=tgBuffCode 
DriveStatus Status with csCode=drvStsCode, status returned 


in csParam through csParam+21 
Advanced Control Calls 
csCode csParam Effect 


Volume IV addition 


5 Verifies disk formatting 

6 integer Formats a disk 

9 integer Controls track cache feature 
21 ptr (long) Fetches hard disk icon 


Volume V addition 


21 ptr (long) Fetches icon for media 
22 ptr (long) Fetches icon for physical drive 
23 long Fetches drive information 
Variables 
BufTgFNum File tags buffer: file number (long) 
BufTgFFlag File tags buffer: flags (word: bit 1=1 if resource fork) 
BufTgFBkNum File tags buffer: logical block number (word) 
BufTgDate File tags buffer: date and time of last modification (long) 


Volume IV addition 


TFSTagData Additional 8 bytes of Hard Disk 20 tag data 
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Further Reference: 


Toolbox Event Manager 

OS Event Manager 

File Manager 

Device Manager 

Technical Note #2, Compatibility Guidelines 

Technical Note #10, Pinouts 

Technical Note #28, Finders and Foreign Drives 
Technical Note #65, Macintosh Plus Pinouts 

Technical Note #70, Forcing Disks to be Either 400K or 800K 
Technical Note #150, Macintosh SE Disk Driver Bug 
Technical Note #255, Macintosh Portable ROM Expansion 
Q & A Stack 

"Macintosh Family Hardware Reference" 


END OF DOCUMENT 
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